home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / cat.n / trace.n < prev    next >
Text File  |  1995-07-25  |  10KB  |  198 lines
  1.  
  2.  
  3.  
  4.      ttttrrrraaaacccceeee((((nnnn))))                     TTTTccccllll (((( ))))                     ttttrrrraaaacccceeee((((nnnn))))
  5.  
  6.  
  7.  
  8.      _________________________________________________________________
  9.  
  10.      NNNNAAAAMMMMEEEE
  11.           trace - Monitor variable accesses
  12.  
  13.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.           ttttrrrraaaacccceeee _o_p_t_i_o_n ?_a_r_g _a_r_g ...?
  15.      _________________________________________________________________
  16.  
  17.  
  18.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  19.           This command causes Tcl commands  to  be  executed  whenever
  20.           certain  operations  are invoked.  At present, only variable
  21.           tracing is implemented. The legal  _o_p_t_i_o_n's  (which  may  be
  22.           abbreviated) are:
  23.  
  24.           ttttrrrraaaacccceeee vvvvaaaarrrriiiiaaaabbbblllleeee _n_a_m_e _o_p_s _c_o_m_m_a_n_d
  25.                Arrange for _c_o_m_m_a_n_d to be  executed  whenever  variable
  26.                _n_a_m_e is accessed in one of the ways given by _o_p_s.  _N_a_m_e
  27.                may refer to a normal variable, an element of an array,
  28.                or  to  an  array as a whole (i.e. _n_a_m_e may be just the
  29.                name of an array, with  no  parenthesized  index).   If
  30.                _n_a_m_e  refers  to a whole array, then _c_o_m_m_a_n_d is invoked
  31.                whenever any element of the array is manipulated.
  32.  
  33.                _O_p_s indicates which operations  are  of  interest,  and
  34.                consists of one or more of the following letters:
  35.  
  36.                     rrrr    Invoke _c_o_m_m_a_n_d whenever the variable is read.
  37.  
  38.                     wwww    Invoke  _c_o_m_m_a_n_d  whenever  the  variable   is
  39.                          written.
  40.  
  41.                     uuuu    Invoke  _c_o_m_m_a_n_d  whenever  the  variable   is
  42.                          unset.   Variables  can  be  unset explicitly
  43.                          with the uuuunnnnsssseeeetttt command,  or  implicitly  when
  44.                          procedures   return   (all   of  their  local
  45.                          variables are  unset).   Variables  are  also
  46.                          unset  when  interpreters  are  deleted,  but
  47.                          traces will not be invoked because  there  is
  48.                          no interpreter in which to execute them.
  49.  
  50.                When the trace triggers, three arguments  are  appended
  51.                to _c_o_m_m_a_n_d so that the actual command is as follows:
  52.  
  53.                     _c_o_m_m_a_n_d _n_a_m_e_1 _n_a_m_e_2 _o_p
  54.                _N_a_m_e_1 and _n_a_m_e_2 give the name(s) for the variable being
  55.                accessed:  if the variable is a scalar then _n_a_m_e_1 gives
  56.                the variable's name and _n_a_m_e_2 is an  empty  string;  if
  57.                the  variable  is an array element then _n_a_m_e_1 gives the
  58.                name of the array and name2 gives the  index  into  the
  59.                array;  if  an  entire  array  is being deleted and the
  60.  
  61.  
  62.      Page 1                                          (printed 7/17/95)
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.      ttttrrrraaaacccceeee((((nnnn))))                     TTTTccccllll (((( ))))                     ttttrrrraaaacccceeee((((nnnn))))
  70.  
  71.  
  72.  
  73.                trace was registered on the overall array, rather  than
  74.                a  single  element, then _n_a_m_e_1 gives the array name and
  75.                _n_a_m_e_2 is an empty string.  _O_p indicates what  operation
  76.                is being performed on the variable, and is one of rrrr, wwww,
  77.                or uuuu as defined above.
  78.  
  79.                _C_o_m_m_a_n_d executes in the same context as the  code  that
  80.                invoked  the  traced  operation:   if  the variable was
  81.                accessed as part of a Tcl procedure, then _c_o_m_m_a_n_d  will
  82.                have  access to the same local variables as code in the
  83.                procedure.  This context  may  be  different  than  the
  84.                context  in  which  the  trace was created.  If _c_o_m_m_a_n_d
  85.                invokes a procedure (which it normally does)  then  the
  86.                procedure  will  have  to  use  uuuuppppvvvvaaaarrrr  or uuuupppplllleeeevvvveeeellll if it
  87.                wishes to access the traced variable.  Note  also  that
  88.                _n_a_m_e_1  may not necessarily be the same as the name used
  89.                to set the trace  on  the  variable;   differences  can
  90.                occur  if the access is made through a variable defined
  91.                with the uuuuppppvvvvaaaarrrr command.
  92.  
  93.                For read and  write  traces,  _c_o_m_m_a_n_d  can  modify  the
  94.                variable  to affect the result of the traced operation.
  95.                If _c_o_m_m_a_n_d modifies the value of a  variable  during  a
  96.                read  or  write  trace,  then  the  new  value  will be
  97.                returned as the result of the  traced  operation.   The
  98.                return value from  _c_o_m_m_a_n_d is ignored except that if it
  99.                returns an error of any sort then the traced  operation
  100.                also  returns  an  error  with  the  same error message  |
  101.                returned by the trace command (this  mechanism  can  be
  102.                used  to  implement  read-only variables, for example).
  103.                For  write  traces,  _c_o_m_m_a_n_d  is  invoked   after   the
  104.                variable's  value  has been changed; it can write a new
  105.                value into the variable to override the original  value
  106.                specified  in  the write operation.  To implement read-
  107.                only variables, _c_o_m_m_a_n_d will have to  restore  the  old
  108.                value of the variable.
  109.  
  110.                While _c_o_m_m_a_n_d is  executing  during  a  read  or  write
  111.                trace, traces on the variable are temporarily disabled.
  112.                This means that reads and  writes  invoked  by  _c_o_m_m_a_n_d
  113.                will  occur  directly, without invoking _c_o_m_m_a_n_d (or any
  114.                other traces) again.  However, if  _c_o_m_m_a_n_d  unsets  the  |
  115.                variable then unset traces will be invoked.
  116.  
  117.                When an  unset  trace  is  invoked,  the  variable  has
  118.                already  been  deleted:  it will appear to be undefined
  119.                with no traces.   If  an  unset  occurs  because  of  a
  120.                procedure return, then the trace will be invoked in the
  121.                variable context of the procedure  being  returned  to:
  122.                the  stack  frame  of  the  returning procedure will no
  123.                longer exist.  Traces are  not  disabled  during  unset
  124.                traces,  so  if  an  unset  trace command creates a new
  125.  
  126.  
  127.  
  128.      Page 2                                          (printed 7/17/95)
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.      ttttrrrraaaacccceeee((((nnnn))))                     TTTTccccllll (((( ))))                     ttttrrrraaaacccceeee((((nnnn))))
  136.  
  137.  
  138.  
  139.                trace and accesses the  variable,  the  trace  will  be
  140.                invoked.  Any errors in unset traces are ignored.        |
  141.  
  142.                If there are multiple traces on  a  variable  they  are
  143.                invoked  in  order  of creation, most-recent first.  If
  144.                one trace returns an error, then no further traces  are
  145.                invoked  for  the  variable.  If an array element has a
  146.                trace set, and there is also a trace set on  the  array
  147.                as  a  whole, the trace on the overall array is invoked
  148.                before the one on the element.
  149.  
  150.                Once created, the trace remains in effect either  until
  151.                the  trace  is  removed  with the ttttrrrraaaacccceeee vvvvddddeeeelllleeeetttteeee command
  152.                described below, until the variable is unset, or  until
  153.                the  interpreter  is  deleted.  Unsetting an element of
  154.                array will remove any traces on that element, but  will
  155.                not remove traces on the overall array.
  156.  
  157.                This command returns an empty string.
  158.  
  159.           ttttrrrraaaacccceeee vvvvddddeeeelllleeeetttteeee _n_a_m_e _o_p_s _c_o_m_m_a_n_d
  160.                If there is a trace  set  on  variable  _n_a_m_e  with  the
  161.                operations  and  command given by _o_p_s and _c_o_m_m_a_n_d, then
  162.                the trace is removed, so that _c_o_m_m_a_n_d will never  again
  163.                be invoked.  Returns an empty string.
  164.  
  165.           ttttrrrraaaacccceeee vvvviiiinnnnffffoooo _n_a_m_e
  166.                Returns a list containing one element  for  each  trace
  167.                currently  set  on  variable _n_a_m_e.  Each element of the
  168.                list is itself a list containing  two  elements,  which
  169.                are  the _o_p_s and _c_o_m_m_a_n_d associated with the trace.  If
  170.                _n_a_m_e doesn't exist or doesn't have any traces set, then
  171.                the result of the command will be an empty string.
  172.  
  173.  
  174.      KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  175.           read, variable, write, trace, unset
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.      Page 3                                          (printed 7/17/95)
  195.  
  196.  
  197.  
  198.